<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Handling failure in Transactional Data Store applications</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="transapp.html" title="Chapter 12.  Berkeley DB Transactional Data Store Applications" />
    <link rel="prev" href="transapp_term.html" title="Terminology" />
    <link rel="next" href="transapp_app.html" title="Architecting Transactional Data Store applications" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Handling failure in Transactional Data Store applications</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="transapp_term.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 12.  Berkeley DB Transactional Data Store Applications </th>
          <td width="20%" align="right"> <a accesskey="n" href="transapp_app.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="transapp_fail"></a>Handling failure in Transactional Data Store applications</h2>
          </div>
        </div>
      </div>
      <p> 
        When building Transactional Data Store applications, there
        are design issues to consider whenever a thread of control
        with open Berkeley DB handles fails for any reason (where a
        thread of control may be either a true thread or a process).
    </p>
      <p> 
        The first case is handling system failure: if the system
        fails, the database environment and the databases may be left
        in a corrupted state. In this case, recovery must be performed
        on the database environment before any further action is
        taken, in order to:
    </p>
      <div class="itemizedlist">
        <ul type="disc">
          <li>
            recover the database environment
            resources,
        </li>
          <li>
            release any locks or mutexes that may have been held
            to avoid starvation as the remaining threads of control
            convoy behind the held locks, and
        </li>
          <li>
            resolve any partially completed operations that may
            have left a database in an inconsistent or corrupted
            state.
        </li>
        </ul>
      </div>
      <p>
        For details on performing recovery, see the <a class="xref" href="transapp_recovery.html" title="Recovery procedures">Recovery procedures</a>. 
    </p>
      <p>
        The second case is handling the failure of a thread of
        control. There are resources maintained in database
        environments that may be left locked or corrupted if a thread
        of control exits unexpectedly. These resources include data
        structure mutexes, logical database locks and unresolved
        transactions (that is, transactions which were never aborted
        or committed). While Transactional Data Store applications can
        treat the failure of a thread of control in the same way as
        they do a system failure, they have an alternative choice, the
        <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV-&gt;failchk()</a> method.
    </p>
      <p> 
        The <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV-&gt;failchk()</a> method will return 
        <a class="link" href="program_errorret.html#program_errorret.DB_RUNRECOVERY">DB_RUNRECOVERY</a> 
        if the database environment is unusable as a result of the thread
        of control failure. (If a data structure mutex or a database write
        lock is left held by thread of control failure, the application
        should not continue to use the database environment, as subsequent
        use of the environment is likely to result in threads of control
        convoying behind the held locks.) The <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV-&gt;failchk()</a> call will
        release any database read locks that have been left held by the
        exit of a thread of control, and abort any unresolved transactions.
        In this case, the application can continue to use the database
        environment.
    </p>
      <p>
        Note that you can optionally cause <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV-&gt;failchk()</a> to broadcast a database
        environment failure to other threads of control by using the
        <code class="literal">--enable-failchk_broadcast</code> flag when you compile
        your Berkeley DB library. If this option is turned on, then all
        threads of control using the database environment will return 
        <a class="link" href="program_errorret.html#program_errorret.DB_RUNRECOVERY">DB_RUNRECOVERY</a>
        when they attempt to obtain a mutex lock. In this situation, a
        <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_FAILCHK_PANIC" class="olink">DB_EVENT_FAILCHK_PANIC</a> or
        <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_MUTEX_DIED" class="olink">DB_EVENT_MUTEX_DIED</a> event will also be raised.
        (You use <a href="../api_reference/C/envevent_notify.html" class="olink">DB_ENV-&gt;set_event_notify()</a> to examine events). 
    </p>
      <p> 
        A Transactional Data Store application recovering from a
        thread of control failure should call <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV-&gt;failchk()</a>, and, if it
        returns success, the application can continue. If <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV-&gt;failchk()</a>
        returns <a class="link" href="program_errorret.html#program_errorret.DB_RUNRECOVERY">DB_RUNRECOVERY</a>, 
        the application should proceed as described for the case of system
        failure.  In addition, threads notified of failure by <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV-&gt;failchk()</a>
        should also proceed as described for the case of system failure.
    </p>
      <p>
        It greatly simplifies matters that recovery may be
        performed regardless of whether recovery needs to be
        performed; that is, it is not an error to recover a database
        environment for which recovery is not strictly necessary. For
        this reason, applications should not try to determine if the
        database environment was active when the application or system
        failed. Instead, applications should run recovery any time the
        <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV-&gt;failchk()</a> method returns <a class="link" href="program_errorret.html#program_errorret.DB_RUNRECOVERY">
        DB_RUNRECOVERY</a>, or, if the application is not
        calling the <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV-&gt;failchk()</a> method, any time any thread of
        control accessing the database environment fails, as well as
        any time the system reboots. 
    </p>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="transapp_term.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="transapp.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="transapp_app.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Terminology </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Architecting Transactional Data
        Store applications</td>
        </tr>
      </table>
    </div>
  </body>
</html>
